mirror of
https://github.com/amark/gun.git
synced 2025-06-04 13:16:44 +00:00
readme update
This commit is contained in:
Mark Nadal
parent
ee919e7076
commit
ce6ce34dce
199
README.md
199
README.md
@ -1,170 +1,89 @@
|
||||
gun [](https://npmjs.org/package/gun) [](https://travis-ci.org/amark/gun) [](https://gitter.im/amark/gun?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
===
|
||||
# gun
|
||||
|
||||
GUN is a realtime, decentralized, offline-first, graph database engine.
|
||||
<a href="https://npmjs.org/package/gun"><img align="right" alt="npm downloads" src="https://img.shields.io/npm/dm/gun.svg?style=flat" /></a>
|
||||
<a href="https://travis-ci.org/amark/gun"><img align="right" alt="Build status" src="https://travis-ci.org/amark/gun.svg?branch=master" /></a>
|
||||
<a href="https://gitter.im/amark/gun?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img align="right" alt="Gitter channel" src="https://badges.gitter.im/Join%20Chat.svg" /></a>
|
||||
|
||||
[](https://youtu.be/-i-11T5ZI9o)
|
||||
GUN is a realtime, distributed, offline-first, graph database engine.
|
||||
|
||||
## Getting Started
|
||||
## But what makes gun **awesome**?
|
||||
|
||||
For the browser, try out this [tutorial](http://gun.js.org/think.html) and then use a [starter template](http://plnkr.co/edit/f1yzn5). This README is for GUN servers.
|
||||
- **Realtime** - GUN shares data across connected peers in real-time. There's no need for plugins, extensions, or anything else, just use gun as directed and enjoy realtime data sharing.
|
||||
- **Distributed** - GUN is peer-to-peer by design and doesn't rely on a central data server. This results in all kinds of data deliciousness, including being able to work offline by default. Peers can be configured into more traditional centralized or federated systems, as appropriate for application needs.
|
||||
- **Graph** - All data in gun is encapsulated as nodes in a graph. Graphs allow data to be related in traditional table formats, as well as tree format, and circular formats. In other words, gun lets your data needs determine your data storage structure.
|
||||
|
||||
If you do not have [node](http://nodejs.org/) or [npm](https://www.npmjs.com/), read [this](https://github.com/amark/gun/blob/master/examples/install.sh) first.
|
||||
Then in your terminal, run:
|
||||
|
||||
```bash
|
||||
npm install gun
|
||||
```
|
||||
|
||||
Now you can require it in the app you want to build.
|
||||
|
||||
```javascript
|
||||
var Gun = require('gun');
|
||||
```
|
||||
|
||||
Once included, initialize a gun instance with a file path or your AWS S3 credentials.
|
||||
|
||||
```javascript
|
||||
var gun = Gun({
|
||||
file: 'data.json',
|
||||
s3: { // Optional!
|
||||
key: '', // AWS Access Key
|
||||
secret: '', // AWS Secret Token
|
||||
bucket: '' // The bucket you want to save into
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
These are the default persistence layers, they are modular and can be replaced by others.
|
||||
|
||||
Using S3 is recommended for deployment, and using a file is recommended for local development only.
|
||||
## Table of Contents
|
||||
- [Demos](#demos)
|
||||
- [Videos](#videos)
|
||||
- [Projects](#gun-projects)
|
||||
- [How to get started](#how-to-get-started)
|
||||
- [Modules](#gun-modules)
|
||||
- [How can I help make gun even more awesome?](#how-can-i-help-make-gun-even-more-awesome)
|
||||
- [License](#license)
|
||||
- [Contributors](#contributors)
|
||||
- [Changelog](#changelog)
|
||||
- [Stay up-to-date](#stay-up-to-date)
|
||||
- **[API Reference](https://github.com/amark/gun/wiki/API-(v0.3.x))** :arrow_upper_right:
|
||||
|
||||
## Demos
|
||||
|
||||
The examples included in this repo are online [here](http://gunjs.herokuapp.com/), you can run them locally by:
|
||||
- [Online example applications](http://gunjs.herokuapp.com/)
|
||||
- The above examples are included in this repo. You can run them locally by running the following commands in your terminal or on your command line:
|
||||
|
||||
```bash
|
||||
npm install gun
|
||||
cd node_modules/gun
|
||||
node examples/http.js 8080
|
||||
```
|
||||
> **Note:** If you don't have [node](http://nodejs.org/) or [npm](https://www.npmjs.com/), read [this](https://github.com/amark/gun/blob/master/examples/install.sh) first.
|
||||
|
||||
Then visit [http://localhost:8080](http://localhost:8080) in your browser. If that did not work it is probably because npm installed it to a global directory. To fix that try `mkdir node_modules` in your desired directory and re-run the above commands. You also might have to add `sudo` in front of the commands.
|
||||
```bash
|
||||
npm install gun
|
||||
cd node_modules/gun
|
||||
node examples/http.js 8080
|
||||
```
|
||||
|
||||
***
|
||||
## WARNINGS
|
||||
### v0.2.0 [](http://waffle.io/amark/gun) [](http://waffle.io/amark/gun) [](http://waffle.io/amark/gun) Status
|
||||
Then visit [http://localhost:8080](http://localhost:8080) in your browser.
|
||||
|
||||
The wire protocol was changed between 0.1.x and 0.2.x, meaning if you upgrade gun your old data might not load properly. If you are listening for errors you will get a `''Not a valid graph!'` but if you are not listening to errors it will be silent, beware of this. Here is a [migration guide](https://github.com/amark/gun/wiki/Migration-Guide) if you are having problems.
|
||||
If that did not work it is probably because npm installed it to a global directory. To fix that try `mkdir node_modules` in your desired directory and re-run the above commands. You also might have to add `sudo` in front of the commands.
|
||||
|
||||
Version 0.2.0 is currently in alpha. Important changes include `.get` to `.val`, `.load` to `.get`, and `.set` to `.put`. Documentation is our current focus, and `.all` functionality will be coming soon. The latest documentation can be found at https://github.com/amark/gun/wiki/0.2.0-API-and-How-to. Please report any issues via https://github.com/amark/gun/issues.
|
||||
### Videos
|
||||
- [Fault tolerance](https://www.youtube.com/watch?v=-i-11T5ZI9o&feature=youtu.be) (01:01)
|
||||
- [Saving relational or document based data](https://www.youtube.com/watch?v=cOO6wz1rZVY&feature=youtu.be) (06:59)
|
||||
- [GUN's YouTube channel](https://www.youtube.com/channel/UCQAtpf-zi9Pp4__2nToOM8g/playlists) also has videos
|
||||
|
||||
GUN is not stable, and therefore should not be trusted in a production environment.
|
||||
***
|
||||
### <a name="gun-projects"></a>Projects
|
||||
- GUN users are encouraged to add their projects to this [running projects list](https://github.com/amark/gun/wiki/projects).
|
||||
|
||||
## [API](https://github.com/amark/gun/wiki/JS-API)
|
||||
## How to get started
|
||||
- Until we complete the [Getting Started with GUN](https://github.com/amark/gun/wiki/getting-started-(v0.3.x)) Guide, please review the [API documentation](https://github.com/amark/gun/wiki/API-(v0.3.x)) and [examples' source code](https://github.com/amark/gun/blob/master/examples).
|
||||
- Check out and add example code [snippets](https://github.com/amark/gun/wiki/snippets-(v0.3.x)) —including micro-modules— to address specific situations.
|
||||
|
||||
Below is a really basic overview of how the gun API works. For a more detailed explanation with many more examples, [check out the wiki](https://github.com/amark/gun/wiki).
|
||||
## <a name="gun-modules"></a>Modules
|
||||
GUN is designed to be as minimal as possible, with any additional functionality being provided via modules. Please refer to the [modules](https://github.com/amark/gun/wiki/modules) page for a list of existing extensions. Please refer to the [gun-extensions](https://github.com/gundb/gun-extensions/issues) repo to see what extensions have been requested or to request an extension.
|
||||
|
||||
## Putting Data
|
||||
## How can I help make gun even more awesome?
|
||||
- Star this repo
|
||||
- Follow us and share your appreciation via [Gitter](https://gitter.im/amark/gun), [Twitter](https://twitter.com/databasegun), [LinkedIn](https://www.linkedin.com/company/gun-inc), and [Facebook](https://www.facebook.com/databasegun)
|
||||
- [Share projects you've written](https://github.com/amark/gun/wiki/projects)
|
||||
- [Build extensions or squish bugs](https://waffle.io/amark/gun)
|
||||
- If you are working on an extension, familiarize yourself with [GUN's Module API](https://github.com/amark/gun/wiki/Building-Modules-for-Gun)
|
||||
|
||||
In gun, it can be helpful to think of everything as field/value pairs. For example, let's say we have a `user` object that looks like this:
|
||||
## License
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "marknadal",
|
||||
"name": "Mark Nadal",
|
||||
"email": "mark@gunDB.io"
|
||||
}
|
||||
```
|
||||
Now, we want to save this object to a key called `'usernames/marknadal'`. We can do that like this:
|
||||
Designed with ♥ by Mark Nadal, the gun team, and many amazing contributors. Liberally licensed under [Zlib / MIT / Apache 2.0](https://github.com/amark/gun/blob/master/LICENSE.md).
|
||||
|
||||
```javascript
|
||||
gun.put({
|
||||
username: "marknadal",
|
||||
name: "Mark Nadal",
|
||||
email: "mark@gunDB.io"
|
||||
}).key('usernames/marknadal');
|
||||
```
|
||||
|
||||
We can also pass `put` a callback that can be used to handle errors:
|
||||
|
||||
```javascript
|
||||
gun.put({
|
||||
username: "marknadal",
|
||||
name: "Mark Nadal",
|
||||
email: "mark@gunDB.io"
|
||||
}, function(err){
|
||||
// Do something to handle the error
|
||||
}).key('usernames/marknadal');
|
||||
```
|
||||
|
||||
### Getting Data
|
||||
|
||||
Once we have some data stored in gun, we need a way to get them out again. Retrieving the data that we just stored would look like this:
|
||||
|
||||
```javascript
|
||||
gun.get('usernames/marknadal').val(function(user){
|
||||
console.log(user.name); // Prints `Mark Nadal` to the console
|
||||
});
|
||||
```
|
||||
|
||||
Basically, this tells gun to check `'usernames/marknadal'`, and then return the object it finds associated with it. For more information, including how to save relational or document based data, [check out the wiki](https://github.com/amark/gun/wiki), or watch this tutorial:
|
||||
|
||||
[](https://youtu.be/cOO6wz1rZVY)
|
||||
|
||||
---
|
||||
|
||||
## YOU
|
||||
|
||||
[Add your project!](https://github.com/amark/gun/wiki/projects)
|
||||
|
||||
Our goal is for GUN to be the easiest database ever,
|
||||
which means if you ever get stuck on something for longer than 5 minutes,
|
||||
let us know so we can help you. Your input is invaluable,
|
||||
as it enables us where to refine GUN. So drop us a line in the [](https://gitter.im/amark/gun?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)! Or join the [mail list](https://groups.google.com/forum/#!forum/g-u-n).
|
||||
## Contributors
|
||||
|
||||
Thanks to the following people who have contributed to GUN, via code, issues, or conversation (this list has quickly become tremendously behind! We'll probably turn this into a dedicated wiki page so you can add yourself):
|
||||
|
||||
[agborkowski](https://github.com/agborkowski); [alexlafroscia](https://github.com/alexlafroscia); [anubiann00b](https://github.com/anubiann00b); [bromagosa](https://github.com/bromagosa); [coolaj86](https://github.com/coolaj86); [d-oliveros](https://github.com/d-oliveros), [danscan](https://github.com/danscan); **[forrestjt](https://github.com/forrestjt) ([file.js](https://github.com/amark/gun/blob/master/lib/file.js))**; [gedw99](https://github.com/gedw99); [HelloCodeMing](https://github.com/HelloCodeMing); **[JosePedroDias](https://github.com/josepedrodias) (graph visualizer)**; **[jveres](https://github.com/jveres) ([todoMVC](https://github.com/jveres/todomvc) [live demo](http://todos.loqali.com/))**; [ndarilek](https://github.com/ndarilek); [onetom](https://github.com/onetom); [phpnode](https://github.com/phpnode); [PsychoLlama](https://github.com/PsychoLlama); **[RangerMauve](https://github.com/RangerMauve) ([schema](https://github.com/gundb/gun-schema))**; [riston](https://github.com/riston); [rootsical](https://github.com/rootsical); [rrrene](https://github.com/rrrene); [ssr1ram](https://github.com/ssr1ram); [Xe](https://github.com/Xe); [zot](https://github.com/zot);
|
||||
[ayurmedia](https://github.com/ayurmedia);
|
||||
|
||||
This list of contributors was manually compiled, alphabetically sorted. If we missed you, please submit an issue so we can get you added!
|
||||
This list of contributors was manually compiled and alphabetically sorted. If we missed you, please submit an issue so we can get you added!
|
||||
|
||||
## Contribute
|
||||
## [Changelog](https://github.com/amark/gun/blob/master/CHANGELOG.md#03)
|
||||
|
||||
Extending GUN or writing modules for it is as simple as:
|
||||
Also see the current [Release List](https://github.com/amark/gun/releases) and [Tag List](https://github.com/amark/gun/tags) for quick access to relevant versions.
|
||||
|
||||
`Gun.on('opt').event(function(gun, opt){ /* Your module here! */ })`
|
||||
==========================
|
||||
<a name="stay-up-to-date"></a>
|
||||
|
||||
We also want our database to be comprehensible, not some magical black box.
|
||||
So often database questions get dismissed with "its complicated hard low level stuff, let the experts handle it".
|
||||
That attitude prevents progress, instead we welcome teaching people and listening to new perspectives.
|
||||
Join along side us in a quest to learn cool things and help others build awesome technology!
|
||||
|
||||
We need help on the following roadmap.
|
||||
|
||||
## Ahead
|
||||
- ~~Realtime push to the browser~~
|
||||
- ~~Persistence in the browser~~
|
||||
- ~~Efficient storage engine~~ [@PsychoLlama](https://github.com/psychollama/gun-level)
|
||||
- Authorization callbacks
|
||||
- Security or ACLs
|
||||
- ~~Schema Validation~~ [@RangerMauve](https://github.com/gundb/gun-schema)
|
||||
- Point of Entry Encryption
|
||||
- ~~Graph manipulation~~
|
||||
- Server to server communication
|
||||
- Test more
|
||||
- WebRTC Transport
|
||||
- LRU or some Expiry (so RAM doesn't asplode)
|
||||
- Bug fixes
|
||||
- Data Structures:
|
||||
- ~~Sets~~ (Table/Collections, Unordered Lists)
|
||||
- CRDTs
|
||||
- OT
|
||||
- Locking / Strong Consistency (sacrifices Availability)
|
||||
- Query:
|
||||
- SQL
|
||||
- MongoDB Query Documents
|
||||
- Neo4j Cypher
|
||||
- LINQ
|
||||
- Gremlin Query Language
|
||||
<a href="https://gitter.im/amark/gun"><img alt="Gitter channel" src="https://badges.gitter.im/Join%20Chat.svg" /></a>
|
||||
[](https://www.youtube.com/channel/UCQAtpf-zi9Pp4__2nToOM8g) [](https://www.linkedin.com/company/gun-inc) [](https://twitter.com/databasegun)
|
||||
50
lib/wsp.js
50
lib/wsp.js
@ -127,45 +127,41 @@
|
||||
key[Gun._.soul] = req.url.query[Gun._.soul];
|
||||
}
|
||||
console.log("tran.get", key);
|
||||
var opt = {};
|
||||
//gun.get(key, function(err, node){
|
||||
(gun.__.opt.wire.get||function(key, cb){cb(null,null)})(key, function(err, node){
|
||||
//tran.sub.scribe(req.tab, graph._[Gun._.soul]);
|
||||
console.log("tran.get", key, "<---", err, node);
|
||||
if(err || !node){
|
||||
if(opt.on && opt.on.off){ opt.on.off() }
|
||||
return cb({headers: reply.headers, body: (err? (err.err? err : {err: err || "Unknown error."}) : null)});
|
||||
}
|
||||
if(Gun.obj.empty(node)){ return cb({headers: reply.headers, body: node}) } // we're out of stuff!
|
||||
|
||||
if(Gun.obj.empty(node)){
|
||||
if(opt.on && opt.on.off){ opt.on.off() }
|
||||
return cb({headers: reply.headers, body: node});
|
||||
} // we're out of stuff!
|
||||
/*
|
||||
(function(chunks){// FEATURE! Stream chunks if the nodes are large!
|
||||
var max = 10;
|
||||
Gun.is.graph(graph, function(node, soul){
|
||||
var chunk = {};
|
||||
if(Object.keys(node).length > max){
|
||||
var count = 0, n = Gun.union.pseudo(soul);
|
||||
Gun.obj.map(node, function(val, field){
|
||||
if(!(++count % max)){
|
||||
console.log("Sending chunk", chunk);
|
||||
cb({headers: reply.headers, chunk: chunk});
|
||||
n = Gun.union.pseudo(soul);
|
||||
chunk = {};
|
||||
}
|
||||
chunk[soul] = n;
|
||||
n[field] = val;
|
||||
(n._[Gun._.HAM] = n._[Gun._.HAM] || {})[field] = ((node._||{})[Gun._.HAM]||{})[field];
|
||||
});
|
||||
if(count % max){ // finish off the last chunk
|
||||
cb({headers: reply.headers, chunk: chunk});
|
||||
(function(chunks){ // FEATURE! Stream chunks if the nodes are large!
|
||||
var max = 10, count = 0, soul = Gun.is.node.soul(node);
|
||||
if(Object.keys(node).length > max){
|
||||
var n = Gun.is.node.soul.ify({}, soul);
|
||||
Gun.obj.map(node, function(val, field){
|
||||
if(!(++count % max)){
|
||||
cb({headers: reply.headers, chunk: n}); // send node chunks
|
||||
n = Gun.is.node.soul.ify({}, soul);
|
||||
}
|
||||
} else {
|
||||
chunk[soul] = node;
|
||||
console.log("Send BLOB", chunk);
|
||||
cb({headers: reply.headers, chunk: chunk});
|
||||
Gun.is.node.state.ify([n, node], field, val);
|
||||
});
|
||||
if(count % max){ // finish off the last chunk
|
||||
cb({headers: reply.headers, chunk: n});
|
||||
}
|
||||
});
|
||||
} else {
|
||||
cb({headers: reply.headers, chunk: node}); // send full node
|
||||
}
|
||||
}([]));
|
||||
*/
|
||||
cb({headers: reply.headers, chunk: node }); // Use this if you don't want streaming chunks feature.
|
||||
});
|
||||
}, opt);
|
||||
}
|
||||
tran.put = function(req, cb){
|
||||
// NOTE: It is highly recommended you do your own PUT/POSTs through your own API that then saves to gun manually.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user