Update documentation

README.md

@@ -1,37 +1,195 @@
 [![Build Status](https://travis-ci.org/CoorpAcademy/squirrel.svg?branch=master)](https://travis-ci.com/CoorpAcademy/squirrel)
 [![Coverage Status](https://coveralls.io/repos/github/CoorpAcademy/squirrel/badge.svg?branch=master)](https://coveralls.io/github/CoorpAcademy/squirrel?branch=master)
 
-# squirrel
-Watch etcd folder and keep it synchronized.
+Keep a replication of ETCD folder locally for low latency querying.
+Provide index system to access a file without scan all nodes tree.
 
-## Install
+# Summary
+
+- [Install](#install)
+- [Usage](#usage)
+  - [Node Interface](#node-interface)
+    - [`get(path)`](#getpath)
+    - [`getBy(index, key)`](#getbyindex-key)
+    - [`getAll(index)`](#getallindex)
+  - [Command Line Interface](#command-line-interface)
+    - [`squirrel-sync`](#squirrel-sync)
+    - [`squirrel-watch`](#squirrel-watch)
+- [Index System](#index-system)
+- [Fallback System](#fallback-system)
+
+# Install
 ```shell
 $ npm install --save @coorpacademy/squirrel
 ```
 
+# Usage
 
-## Usage
-### Command Line Interface
+## Node Interface
 
+```JavaScript
+const squirrel = createSquirrel({
+    hosts: 'http://localhost:2379',
+    auth: null,
+    ca: null,
+    key: null,
+    cert: null,
+
+    cwd: '/',
+    fallback: '/tmp/squirrel.json',
+    indexes: ['foo', 'bar.baz']
+});
 ```
-squirrel-sync --hosts localhost:2379,localhost:2379 ./my-folder /etcd-folder
-squirrel-watch --hosts localhost:2379,localhost:2379 /etcd-folder
+
+Options:
+- `hosts`: ETCD hosts. [more](https://github.com/stianeikeland/node-etcd/#etcdhosts--1270012379-options)
+- `auth`: A hash containing `{user: "username", pass: "password"}` for basic auth. [more](https://github.com/stianeikeland/node-etcd/#constructor-options)
+- `ca`: Ca certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options)
+- `key`: Client key. [more](https://github.com/stianeikeland/node-etcd/#constructor-options)
+- `cert`: Client certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options)
+- `cwd`: ETCD current working directory.
+- `fallback`: Temporary file to save ETCD replicat.
+- `indexes`: Array of key to index.
+
+### Methods
+
+Consider the following folder:
+
+
+```Bash
+/
+├── bar
+│   └── baz   { "bar": { "baz": "qux" } }
+└── foo       { "foo": "bar" }
 ```
 
-### Retrieve a Client
+#### `get(path)`
+
+Get file by path. Return `Promise`;
 
+- `path` (String): the path of the file to get.
 
+```JavaScript
+const foo = await squirrel.get('/foo');
+console.log(foo); // { "foo": "bar" }
 
-## Test
-You may run test with
+const barBaz = await squirrel.get('/bar/baz');
+console.log(barBaz); // { "bar": { "baz": "qux" } }
 ```
-$ npm test
+
+#### `getBy(index, key)`
+
+Get by index value. Return `Promise`;
+
+- `index` (String): the path of the property to get. It need to be declare in [`indexes`'s options](#node-interface)
+- `key` (String): the value to match
+
+```JavaScript
+const foo = await squirrel.getBy('foo', 'bar');
+console.log(foo); // { "foo": "bar" }
+
+const barBaz = await squirrel.getBy('bar.baz', 'qux');
+console.log(barBaz); // { "bar": { "baz": "qux" } }
+```
+
+Field can be nested, as described by [`_.get`](https://lodash.com/docs#get).
+
+#### `getAll(index)`
+
+Get index Map. Return `Promise`;
+
+- `index` (String): the path of the property to get. It need to be declare in [indexes's options](#node-interface)
+
+```JavaScript
+const foo = await squirrel.getAll('foo');
+console.log(foo); // { "bar": { "foo": "bar" } }
+
+const barBaz = await squirrel.getAll('bar.baz');
+console.log(barBaz); // { "qux": { "bar": { "baz": "qux" } } }
+```
+
+## Command Line Interface
+
+### `squirrel-sync`
+
+Synchronise FS folder with ETCD folder.
+
+```Bash
+$ squirrel-sync --hosts localhost:2379 ./fs-folder /etcd-folder
+```
+
+### `squirrel-watch`
+
+Watch ETCD folder change.
+
+```Bash
+$ squirrel-watch --hosts localhost:2379 /etcd-folder
+```
+
+### Arguments
+
+- `--hosts="host1,host2"`: ETCD hosts. [more](https://github.com/stianeikeland/node-etcd/#etcdhosts--1270012379-options)
+- `--ca=/file.ca`: Ca certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options)
+- `--key=/file.key`: Client key. [more](https://github.com/stianeikeland/node-etcd/#constructor-options)
+- `--cert=/file.cert`: Client certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options)
+
+# Index System
+
+Squirrel allow to put JSON in file. In this case, it could be indexes to access directly. Consider the following ETCD directory.
+
+```Bash
+/
+├── file1 { "foo": "bar" }
+├── file2 { "foo": "baz" }
+└── file3 { "foo": "qux" }
+```
+
+First at all, we should indicate to squirrel which path we want to index.
+
+```JavaScript
+const squirrel = createSquirrel({
+  indexes: ['foo']
+});
+```
+
+Now, we can get `file1` by its `foo` value.
+
+```JavaScript
+const file1 = await squirrel.getBy('foo', 'bar');
+console.log(file1); // { "foo": "bar" }
+```
+
+We can also get the map value of the index.
+
+```JavaScript
+const fooIndex = await squirrel.getAll('foo');
+console.log(fooIndex);
+/*
+{
+  "bar": { "foo": "bar" },
+  "baz": { "foo": "baz" },
+  "qux": { "foo": "qux" }
+}
+ */
 ```
 
-Please note that test use an actual etcd service
+If two files have the same index's value, squirrel keep one of both.
 
+Squirrel scans all files, no matter their deep, which contain a JSON value.
 
+Index could be a complex path, as long as it work with [`_.get`](https://lodash.com/docs#get).
 
+# Fallback System
+
+By declaring `fallback` path, Squirrel is able to save its state every time it changes and to restore it to be faster available on start even if ETCD isn't available.
+
+# Test
+
+You may run tests with
+
+```Bash
+$ npm test
+```
 
-## [Marble](./MARBLE.md)
+# [Marble](./MARBLE.md)
 

docker-compose.yml

@@ -3,4 +3,4 @@ etcd:
   ports:
     - "2379:2379"
     - "4001:4001"
-  command: -listen-client-urls 'http://0.0.0.0:2379,http://0.0.0.0:4001' -advertise-client-urls 'http://0.0.0.0:2379,http://0.0.0.0:4001'
+  command: etcd --listen-client-urls 'http://0.0.0.0:2379' --advertise-client-urls 'http://0.0.0.0:2379'