mirror of
https://github.com/amark/gun.git
synced 2025-03-30 15:08:33 +00:00
Revised Alex's wonderful new README
This commit is contained in:
Mark Nadal
parent
19b5b89b7c
commit
fb181d9a6f
72
README.md
72
README.md
@ -1,24 +1,15 @@
|
||||
gun [](https://travis-ci.org/amark/gun)
|
||||
===
|
||||
|
||||
FOR MHACKS!
|
||||
===
|
||||
I'll be filling this in with help for you in just a moment!
|
||||
|
||||
If you need any help with HTML/CSS/JS just text me 760.689.2468 or email mark@gunDB.io
|
||||
|
||||
PRIZE: Win 2 Adult Electric Scooters! To help you zip around town/campus. :)
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
Assuming you already have [node](http://nodejs.org/) and [npm](https://www.npmjs.com/) installed, install GunDB:
|
||||
If you do not have [node](http://nodejs.org/) or [npm](https://www.npmjs.com/), get started [here](https://github.com/amark/gun/blob/master/examples/start.sh) first. Then run this in your terminal:
|
||||
|
||||
```bash
|
||||
$ npm install gun
|
||||
npm install gun
|
||||
```
|
||||
|
||||
Then, you can require it in your app.
|
||||
Now you can require it in the app you want to build.
|
||||
|
||||
```javascript
|
||||
var Gun = require('gun');
|
||||
@ -26,39 +17,39 @@ var Gun = require('gun');
|
||||
|
||||
Once included, initialize a gun instance with your AWS S3 credentials.
|
||||
|
||||
```JavaScript
|
||||
```javascript
|
||||
var gun = Gun({
|
||||
s3: {
|
||||
key: '', // AWS Access Key
|
||||
secret: '', // AWS Secret Token
|
||||
bucket: '' // The bucket you want to save into
|
||||
}});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
S3 is the default persistence layer, it can be replaced with others.
|
||||
|
||||
Currently, gun is only key/value but graph support is coming soon.
|
||||
|
||||
Save your first object, and create a reference to it.
|
||||
Now you can save your first object, and create a reference to it.
|
||||
|
||||
```javascript
|
||||
gun.set({ hello: 'world' }).key('my/first/data');
|
||||
```
|
||||
|
||||
Now, altogether, with the node hello world web server that replies with your data.
|
||||
Altogether, try it with the node hello world web server which will reply with your data.
|
||||
|
||||
```JavaScript
|
||||
```javascript
|
||||
var Gun = require('gun');
|
||||
var gun = Gun({
|
||||
s3: {
|
||||
key: '', // AWS Access Key
|
||||
secret: '', // AWS Secret Token
|
||||
bucket: '' // The bucket you want to save into
|
||||
}});
|
||||
key: '', // AWS Access Key
|
||||
secret: '', // AWS Secret Token
|
||||
bucket: '' // The bucket you want to save into
|
||||
}
|
||||
});
|
||||
gun.set({ hello: 'world' }).key('my/first/data');
|
||||
|
||||
var http = require('http');
|
||||
http.createServer(function (req, res) {
|
||||
http.createServer(function(req, res){
|
||||
gun.load('my/first/data', function(err, data){
|
||||
res.writeHead(200, {'Content-Type': 'application/json'});
|
||||
res.end(JSON.stringify(data));
|
||||
@ -67,15 +58,15 @@ http.createServer(function (req, res) {
|
||||
console.log('Server running at http://127.0.0.1:1337/');
|
||||
```
|
||||
|
||||
Now fire up your browser and hit that URL - you'll see your data, plus some gun specific metadata.
|
||||
Fire up your browser and hit that URL - you'll see your data, plus some gun specific metadata.
|
||||
|
||||
## API
|
||||
|
||||
Below is a really basic overview of how the GunDB API works. For a more detailed explanation with many more examples, [check out the wiki](#).
|
||||
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).
|
||||
|
||||
## Setting Values
|
||||
## Setting Data
|
||||
|
||||
In GunDB, it can be helpful to think of everything as a key-value pair. For example, let's say we have a `user` object that looks like this:
|
||||
In gun, it can be helpful to think of everything as a field/value pairs. For example, let's say we have a `user` object that looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -84,7 +75,7 @@ In GunDB, it can be helpful to think of everything as a key-value pair. For exa
|
||||
"email": "mark@gunDB.io"
|
||||
}
|
||||
```
|
||||
Now, we want to save this object to a key called `usernames/marknadal`. We can do that like this:
|
||||
Now, we want to save this object to a key called `usernames/marknadal`. We can do that like this:
|
||||
|
||||
```javascript
|
||||
gun.set({
|
||||
@ -101,30 +92,41 @@ gun.set({
|
||||
username: "marknadal",
|
||||
name: "Mark Nadal",
|
||||
email: "mark@gunDB.io"
|
||||
}, function(error) {
|
||||
}, function(err){
|
||||
// Do something to handle the error
|
||||
}).key('usernames/marknadal');
|
||||
```
|
||||
|
||||
### Getting Values
|
||||
### Getting Data
|
||||
|
||||
Once we have some values stored into GunDB, we need a way to get them out again. Retrieving the data that we just stored would look like this:
|
||||
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
|
||||
get.load('usernames/marknadal').get(function(user) {
|
||||
gun.load('usernames/marknadal').get(function(user){
|
||||
console.log(user.name); // Prints `Mark Nadal` to the console
|
||||
});
|
||||
```
|
||||
|
||||
Basically, this tells GunDB to check `usernames/marknadal`, and then return the object it finds associated with it. For more information, including object relationships and how to handle unset keys, [check out the wiki](#).
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
## YOU
|
||||
We're just getting started and gun is foremost designed to be accessible and modular, because the database industry will never make any progress unless we can be more open and approachable. Our goal is to make everybody experts by actually explaining concepts rather than being dismissive with "its complicated hard low level stuff, let the experts handle it." So join the community, learn cool things, and contribute modules and plugins!
|
||||
We're just getting started, so join us! Being lonely is never any fun, especially when programming.
|
||||
I want to help you, because my goal is for GUN to be the easiest database ever.
|
||||
That means if you ever get stuck on something for longer than 5 minutes,
|
||||
you should talk to me so I can help you solve it.
|
||||
Your input will then help me improve gun.
|
||||
We also really open to contributions! GUN is easy to extend and customize:
|
||||
|
||||
`Gun.on('opt').event(function(gun, opt){ /* Your module here! */ })`
|
||||
|
||||
It is also important to us that your database is not a magical black box.
|
||||
So often our questions get dismissed with "its complicated hard low level stuff, let the experts handle it."
|
||||
And we do not think that attitude will generate any progress for people.
|
||||
Instead, we want to make everyone an expert by actually getting really good at explaining the concepts.
|
||||
So join our community, in the quest of learning cool things and helping yourself and others build awesome technology.
|
||||
|
||||
Google Group: https://groups.google.com/forum/#!forum/g-u-n
|
||||
|
||||
## Ahead
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user