Introduction - amark/gun GitHub Wiki

Learn answers to all your questions in THE INTERACTIVE TUTORIAL! Or read along:

GUN is a small, easy, and fast protocol for syncing data. Because GUN is small, it can be added to your app to improve a single feature. But because GUN is easy, it can also replace hundreds or thousands of lines of code, networking calls, storage boilerplate, pub/sub routing, cache invalidation, and more. The power of GUN is that it abstracts this complexity into a unified simple API that is very different than traditional systems, with the aim of making it easy to build cool apps quickly.

The best way to think about GUN is synchronizing video game state: In 2 lines of code we can gun.get('thing').put({x: 0.01, y: 0.02, z: 0.03}) to send updates and gun.get('thing').on(data => object.moveTo(data.x, data.y, data.z)) to read it on another machine:

But it is also important to note that the data will stay there on refresh, even if you're offline! Lastly, remember that .put({x: 0.09}) merges with the existing data. This is the basics of GUN. Jump to a complete Hello World example in 9 lines or (we recommend) you read the rest of this page first.

GUN supports more than just key/value pairs, it is a graph database that can store SQL-like tables, JSON-like documents, files and livestreaming video, plus relational and hypergraph data!

Beware! Anyone can edit the data by default - to fix this, we have to use the User system. GUN is a universal graph which has 3 logical "spaces" protected by SEA:

• Public Space. Anyone can add, change, or remove data from here. Think of it as a giant wiki.

Note: Some data here may be encrypted such that the content stays secret, but it can always be overwritten. Imagine in real life someone hides a prize in a vault at the beach: Once it is found it may be damaged or moved, but only a person who knows the key can unlock it.

• User Space. This data can only be be changed, added or removed, by the owner. The data can be either private or publicly readable.

Note: Data is cryptographically owned by the user, there is no "app admin" or "website owner", this may change how you build apps but it guarantees better safety. Owners can authorize or give other users permission to edit the owner's data. Again, the owner does this, not the app developer or database admin.

• Frozen Space. This data cannot be changed or removed, only added to. Nobody owns this data.

Note: If nobody stores the data it may be forgotten, if the peers that store it are offline the data may not be found until they are online again. This is true of data in any space though.

Data can be in graphs that link across different spaces. So don't assume data is only in one space! For instance, user data can point to public data which can be edited by anyone, just not the link itself. Likewise, public data could link to frozen or user data, but anyone could edit the link itself. One very powerful combination is frozen links to user data, nobody can edit the link but the data itself can be updated by the owner.

gun.get('#users').map().get('country').on(data => console.log(data))

Pretend that #users is a frozen list where each item links to a user profile. Rather than a user saving {name: "Alice", country: "USA"} to their profile, they could instead link to the public wiki about their country. Now our query will get the the country data of each user, like {name: "United States of America", code: "USA", population: 300,000,000} as it is updated in realtime.

Before going further, it is important you understand how GUN uses cryptography to secure data, not backend servers. Check out our 1min animated cartoon explainers to help you build apps with better security. Next let's cover the "no backend" idea:

The universal GUN graph is distributed across all peers participating in the network. Browser peers use localStorage or IndexedDB to store only a subset of the graph they are subscribed to, synced using WebRTC, Websockets, or other transports. The same browser code also runs in NodeJS with adapter plugins for fs, S3-like storage backups, UDP multicast, and other features that let it stay in "relay" mode only or to store everything.

The whole database is considered to be the union of all peers' graphs. All peers help cache and sync data, even the browsers host and serve data to peers they are directly or indirectly connected to. No one machine controls the system. Apps do not own users, users own themselves.

You probably have more questions now than less. That is good, but let's code first, then come back to answers after the Next Steps.

• Follow THE INTERACTIVE TUTORIAL!
• Move to HOW TO INSTALL GUN.