gun Documentation

File: README.md Copy Chapter

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 Copy Chapter

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.

• An online demo of the examples are available here: http://try.axe.eco/
• Or write a quick app: (try now in a playground)

<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: "[email protected]",
});

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. :)

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 Copy Section

• Join others in sponsoring code: https://www.patreon.com/gunDB !
• Ask questions: http://stackoverflow.com/questions/tagged/gun ?
• Found a bug? Report at: https://github.com/amark/gun/issues ;
• Need help? Chat with us: http://chat.gun.eco .

History Copy Section

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 Copy Chapter

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 Copy Chapter

You will need to npm install 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 Copy Chapter

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 Copy Chapter

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 Copy Section

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](https://www.trydome.io/) Copy Section

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

[Heroku](https://www.heroku.com/) Copy Section

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](https://www.zeet.co/) Copy Section

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

[Docker](https://www.docker.com/) Copy Section

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

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 Copy Chapter

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

Openly licensed under Zlib / MIT / Apache 2.0.

YouTube . Twitter

File: examples/angular/README.md Copy Chapter

Angular

This project was generated with Angular CLI version 1.0.0.

Development server Copy Chapter

Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Code scaffolding Copy Chapter

Run ng generate component component-name to generate a new component. You can also use ng generate directive/pipe/service/class/module.

Build Copy Chapter

Run ng build to build the project. The build artifacts will be stored in the dist/ directory. Use the -prod flag for a production build.

Running unit tests Copy Chapter

Run ng test to execute the unit tests via Karma.

Running end-to-end tests Copy Chapter

Run ng e2e to execute the end-to-end tests via Protractor.
Before running the tests make sure you are serving the app via ng serve.

Further help Copy Chapter

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.

File: examples/react/README.md Copy Chapter

You can use todo.html as a project template to get started with React + GUN.

It is an extremely simple in-memory only todo app that you can try here.

There are some other simple examples in the src folder.

If you want to see next level stuff, check out any of Nick's React apps.

File: examples/react-native/README.md Copy Chapter

Gun on react-native!

running the demo Copy Section

1. do yarn install on the directory of the demo examples/react-native
2. run the demo with react-native run-ios or react-native run-android

debugging Copy Section

i would recommend using react-native-debugger but you can use chrome's debugger as well

• ios: cmd+D then Debug JS Remotely
• android: cmd+M then Debug JS Remotely

now you have access to the gun globals on the console which are `gun` -> the root gun `user` -> the gun user Copy Chapter

how it all of this is done

since react-native doesnt provide the crypto module that we desire the most and all of the packages are incompatible with react-native/sea, and so to get sea.js working we use a webview(react-native browser) and bridge the crypto module from that browser to the global window and thats exactly what webview-crypto does, thanks to webview-crypto repo, the webview-crypto provided in this repo is somewhat the same but modified to get it working and mostly compatible with sea/react-native (even though there is a polyfiller for that but it just doesnt work ;/).

File: lib/text-encoding/README.md Copy Chapter

text-encoding

This is a polyfill for the Encoding Living
Standard API for the Web, allowing
encoding and decoding of textual data to and from Typed Array buffers
for binary data in JavaScript.

By default it adheres to the spec and does not support encoding to
legacy encodings, only decoding. It is also implemented to match the
specification's algorithms, rather than for performance. The intended
use is within Web pages, so it has no dependency on server frameworks
or particular module schemes.

Basic examples and tests are included.

Install Copy Section

There are a few ways you can get and use the text-encoding library.

HTML Page Usage Copy Section

Clone the repo and include the files directly:

<script src="encoding-indexes.js"></script>
  <script src="encoding.js"></script>

This is the only use case the developer cares about. If you want those
fancy module and/or package manager things that are popular these days
you should probably use a different library.

Package Managers

The package is published to npm and bower as text-encoding.
Use through these is not really supported, since they aren't used by
the developer of the library. Using require() in interesting ways
probably breaks. Patches welcome, as long as they don't break the
basic use of the files via <script>.

API Overview Copy Section

Basic Usage

var uint8array = new TextEncoder().encode(string);
  var string = new TextDecoder(encoding).decode(uint8array);

Streaming Decode

var string = "", decoder = new TextDecoder(encoding), buffer;
  while (buffer = next_chunk()) {
    string += decoder.decode(buffer, {stream:true});
  }
  string += decoder.decode(); // finish the stream

Encodings Copy Section

All encodings from the Encoding specification are supported:

utf-8 ibm866 iso-8859-2 iso-8859-3 iso-8859-4 iso-8859-5 iso-8859-6
iso-8859-7 iso-8859-8 iso-8859-8-i iso-8859-10 iso-8859-13 iso-8859-14
iso-8859-15 iso-8859-16 koi8-r koi8-u macintosh windows-874
windows-1250 windows-1251 windows-1252 windows-1253 windows-1254
windows-1255 windows-1256 windows-1257 windows-1258 x-mac-cyrillic
gb18030 hz-gb-2312 big5 euc-jp iso-2022-jp shift_jis euc-kr
replacement utf-16be utf-16le x-user-defined

(Some encodings may be supported under other names, e.g. ascii,
iso-8859-1, etc. See Encoding for
additional labels for each encoding.)

Encodings other than utf-8, utf-16le and utf-16be require
an additional encoding-indexes.js file to be included. It is rather
large (596kB uncompressed, 188kB gzipped); portions may be deleted if
support for some encodings is not required.

Non-Standard Behavior Copy Section

As required by the specification, only encoding to utf-8 is
supported. If you want to try it out, you can force a non-standard
behavior by passing the NONSTANDARD_allowLegacyEncoding option to
TextEncoder and a label. For example:

var uint8array = new TextEncoder(
  'windows-1252', { NONSTANDARD_allowLegacyEncoding: true }).encode(text);

But note that the above won't work if you're using the polyfill in a
browser that natively supports the TextEncoder API natively, since the
polyfill won't be used!

You can force the polyfill to be used by using this before the polyfill:

<script>
window.TextEncoder = window.TextDecoder = null;
</script>

To support the legacy encodings (which may be stateful), the
TextEncoder encode() method accepts an optional dictionary and
stream option, e.g. encoder.encode(string, {stream: true}); This
is not needed for standard encoding since the input is always in
complete code points.