Merge pull request #14 from ipfs/doc/update

update documentation

README.md

@@ -1,50 +1,100 @@
 js-ipfs-repo
 ============
 
+> Implementation of the IPFS repo spec (https://github.com/ipfs/specs/tree/master/repo) in JavaScript
 
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) [![Build Status](https://travis-ci.org/ipfs/js-ipfs-repo.svg)](https://travis-ci.org/ipfs/js-ipfs-repo) ![](https://img.shields.io/badge/coverage-53%25-yellow.svg?style=flat-square) [![Dependency Status](https://david-dm.org/diasdavid/js-peer-id.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-repo) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
 
-> Implementation of the IPFS repo spec (https://github.com/ipfs/specs/tree/master/repo) in JavaScript
+## Description
+
+This is the implementation of the [IPFS repo spec](https://github.com/ipfs/specs/tree/master/repo) in JavaScript.
+
+## Architecture
+
+```bash
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+  interface defined by Repo Spec
+├─────────────────────────────────┤
+│                                 │                                  ┌──────────────────────┐
+│                                 │                                  │ abstract-blob-store  │
+│           IPFS REPO             │─────────────────────────────────▶│     interface        │
+│                                 │                                  ├──────────────────────┤
+│                                 │                                  │      locks           │
+└─────────────────────────────────┘                                  └──────────────────────┘
+                 │
+      ┌──────────┴────┬───────────────┬───────────────┬───────────────┬───────────────┐
+      ▼               ▼               ▼               ▼               ▼               ▼
+┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
+│ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │
+│ -blog     │   │ -blog     │   │ -blog     │   │ -blog     │   │ -blog     │   │ -blog     │
+│ -store    │   │ -store    │   │ -store    │   │ -store    │   │ -store    │   │ -store    │
+│ interface │   │ interface │   │ interface │   │ interface │   │ interface │   │ interface │
+├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤
+│           │   │           │   │           │   │           │   │           │   │           │
+│   keys    │   │  config   │   │ datastore │   │ datastore │   │   logs    │   │  version  │
+│           │   │           │   │           │   │ -legacy   │   │           │   │           │
+└───────────┘   └───────────┘   └───────────┘   └───────────┘   └───────────┘   └───────────┘
+```
 
-## API
+IPFS repo exposes a well defined interface by the Repo Spec. Each of the individual repos has an interface defined by [abstract-blob-store](https://github.com/maxogden/abstract-blob-store), this enables us to make IPFS repo portable (running on Node.js vs the browser) and accept different types of storage mechanisms for each repo (fs, levelDB, etc).
 
-### Repo
+## Good to know (historical context)
 
-Constructor, accepts a path and options:
+- The datastore folder holds the legacy version of datastore, still built in levelDB, there is a current endeavour of pushing it to fs completely.
+- The blocks folder is the current version of datastore.
+- The keys repo doesn't exist yet, as the private key is simply stored inside config
 
-```js
-var Repo = require('js-ipfs-repo')
-var repo = new Repo('/Users/someone/.ipfs', {adaptor: 'fs'})
+## Usage
+
+### Install
+
+Standard Node.js way.
+
+```bash
+$ npm i ipfs-repo
 ```
 
-Options:
+### Repo
 
-  - `adaptor`: String with the adaptor. Defaults to `fs`
+Constructor, accepts a path and options:
 
-### version
+```js
+var IPFSRepo = require('js-ipfs-repo')
+var repo = new IPFSRepo('/Users/someone/.ipfs', {
+  stores: {
+    keys: <something that implements abstract-blob-store>,
+    config: <something that implements abstract-blob-store>,
+    datastore: <something that implements abstract-blob-store>,
+    logs: <something that implements abstract-blob-store>,
+    locks: <something that implements abstract-blob-store>,
+    version: <something that implements abstract-blob-store>
+  }})
+```
 
-Read/Write the version number of that repository.
+You can check if the repo you are going to access already exists on the path you passed to the constructor by:
 
 ```js
-repo.version.read(function (err, num) {
-  console.log(err, num) // => 2
+repo.exists(function (err, exists) {
+  // exists is a boolean value
 })
+```
 
-repo.version.write(3, function (err) {
-  console.log(err)
-})
+If the repo doesn't exist yet, you can start it by executing the `init` cuntion
+
+```js
+repo.init(opts, function (err) {})
 ```
 
-### api
+### version
 
-Read/Write the JSON configuration for that repository.
+Read/Write the version number of that repository.
 
 ```js
-repo.api.read(function (err, multiaddr) {
-  console.log(err, multiaddr)
+repo.version.get(function (err, version) {
+  console.log(err, num) // => 2
 })
 
-repo.api.write('/ip4/127.0.0.1/tcp/5001', function (err) {
+repo.version.set(3, function (err) {
   console.log(err)
 })
 ```
@@ -63,50 +113,54 @@ repo.config.write({foo: 'bar'}, function (err) {
 })
 ```
 
-### blocks
+### datastore
 
 Store data on the block store.
 
 ```js
-repo.blocks.read('12200007d4e3a319cd8c7c9979280e150fc5dbaae1ce54e790f84ae5fd3c3c1a0475', function (err, buff) {
+repo.datastore.read('12200007d4e3a319cd8c7c9979280e150fc5dbaae1ce54e790f84ae5fd3c3c1a0475', function (err, buff) {
   console.log(err)
 })
 ```
 
 ```js
-repo.blocks.write(buff, function (err, buffer) {
+repo.datastore.write(buff, function (err, buffer) {
   console.log(buff.toString('utf-8'), err)
 })
 ```
 
-### repo
+### datastore legacy
 
-Read/Write the `repo.lock` file.
+> WIP
 
 ```js
-repo.repo.read(function (err, content) {
-  console.log(err, content)
-})
+repo.datastoreLegacy
+```
 
-repo.repo.write('foo', function (err) {
-  console.log(err)
-})
+```js
+repo.datastoreLegacy
 ```
 
-## Adaptors
+### locks
 
-By default it will use the `fs-repo` adaptor. Eventually we can write other adaptors
-and make those available on configuration.
+> **Note: You shouldn't need to use this. It is used internally**
 
-### fs-repo
+Read/Write the `repo.lock` file.
+
+```js
+repo.locks.lock(function (err) {})
+
+repo.locks.unlock(function (err) {})
+```
 
-The default adaptor. Uses the `repo.lock` file to ensure there are no simultaneous reads
-nor writes. Uses the `fs-blob-store`.
+### logs
 
-### memory-repo
+> WIP (also not available in go-ipfs at the moment)
 
-Ideal for testing purposes. Uses the `abstract-blob-store`.
+## Contribute
 
-## Tests
+There is some ways you can make this module better:
 
-Help us make more tests! Also, enabling them to be run in Node.js and the Browser.
+- You can consult our open issues and take on one of them
+- Make the tests better
+- Make the tests work in the Browser

graphs/arch.txt

@@ -0,0 +1,22 @@
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+  interface defined by Repo Spec
+├─────────────────────────────────┤
+│                                 │                                  ┌──────────────────────┐
+│                                 │                                  │ abstract-blob-store  │
+│           IPFS REPO             │─────────────────────────────────▶│     interface        │
+│                                 │                                  ├──────────────────────┤
+│                                 │                                  │      locks           │
+└─────────────────────────────────┘                                  └──────────────────────┘
+                 │
+      ┌──────────┴────┬───────────────┬───────────────┬───────────────┬───────────────┐
+      ▼               ▼               ▼               ▼               ▼               ▼
+┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
+│ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │
+│ -blog     │   │ -blog     │   │ -blog     │   │ -blog     │   │ -blog     │   │ -blog     │
+│ -store    │   │ -store    │   │ -store    │   │ -store    │   │ -store    │   │ -store    │
+│ interface │   │ interface │   │ interface │   │ interface │   │ interface │   │ interface │
+├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤
+│           │   │           │   │           │   │           │   │           │   │           │
+│   keys    │   │  config   │   │ datastore │   │ datastore │   │   logs    │   │  version  │
+│           │   │           │   │           │   │ -legacy   │   │           │   │           │
+└───────────┘   └───────────┘   └───────────┘   └───────────┘   └───────────┘   └───────────┘

src/stores/config.js

@@ -1,6 +1,6 @@
 module.exports = function (store) {
   return {
-    read: function (cb) {
+    get: function (cb) {
       return store.read('config', function (err, content) {
         if (err) return cb(err)
 
@@ -12,7 +12,7 @@ module.exports = function (store) {
       })
     },
 
-    write: function (content, cb) {
+    set: function (content, cb) {
       return store.write('config', JSON.stringify(content), cb)
     }
   }

tests/repo-test.js

@@ -85,10 +85,9 @@ describe('IPFS Repo Tests', function () {
     })
   })
 
-  describe('api', function () {})
   describe('config', function () {
     it.skip('get config', function (done) {
-      repo.config.read(function (err, config) {
+      repo.config.get(function (err, config) {
         expect(err).to.equal(null)
         expect(config).to.be.a('object')
         done()